TeamA

id: decision-1 title: Use Tailwind CSS v4 for web UI development date: '2025-06-22' status: proposed

Context

The web UI implementation for Backlog.md requires a CSS framework. Tailwind CSS v4 was recently released with significant breaking changes from v3. Given that AI agents may have knowledge cutoffs that include Tailwind v3 instructions, we need clear guidance to prevent setup confusion.

Decision

We will use Tailwind CSS v4 for all web UI development in this project.

Key Requirements:

Use tailwindcss@next and @tailwindcss/vite@next packages
CSS-first configuration using @import "tailwindcss" syntax
No tailwind.config.js file - configuration goes in CSS using @theme
Use @tailwindcss/vite plugin instead of PostCSS setup

Rationale:

Modern approach: v4 provides better performance and developer experience
CSS-first: More intuitive configuration directly in CSS
Future-proofing: Latest version with ongoing support
Vite integration: First-party Vite plugin for optimal performance

Setup Instructions

Installation

bun add -D tailwindcss@next @tailwindcss/vite@next

Vite Configuration

// vite.config.ts
import tailwindcss from "@tailwindcss/vite"

export default defineConfig({
  plugins: [react(), tailwindcss()]
})

CSS Configuration

/* src/index.css */
@import "tailwindcss";

@theme {
  /* Custom theme configuration */
  --color-primary: #3b82f6;
}

❌ DON'T DO (Tailwind v3):

@tailwind base;
@tailwind components;
@tailwind utilities;

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{js,jsx,ts,tsx}'],
  theme: { extend: {} }
}

✅ DO THIS (Tailwind v4):

@import "tailwindcss";
@theme {
  --color-primary: #3b82f6;
}

Consequences

Positive:

Better Performance: v4's Vite plugin provides faster builds
Simplified Setup: No PostCSS configuration needed
CSS-first Config: More intuitive than JavaScript configuration
Automatic Content Detection: No need to manually configure content paths
Modern Features: Built-in container queries, 3D transforms, enhanced gradients

Negative:

Breaking Changes: Cannot use v3 documentation/examples without adaptation
Learning Curve: Team needs to understand v4-specific syntax
Potential Issues: As a newer version, may have undiscovered edge cases

Mitigation:

Clear documentation with v3 vs v4 comparisons
Reference this decision in all relevant tasks
Provide specific examples for common use cases